Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
It’s the responsibility of the root part of the active window to handle the Print command of the Document menu. The Shell will automatically dispatch this menu command to the HandleEvent method of the owning part of the active window’s root frame. Since any part can become the root of a window (via the View As Window command, or by dragging a frame to the Finder and double-clicking it), all part handlers should support printing unless there is some special reason why printing makes no sense for that particular content.
Of course, embedded parts will also be printed as the result of a Print command. But for an embedded part it’s a lesser task; the part will be told to open a new frame / facet on a printing canvas, and will then be told to draw itself onto that canvas. If a part wants to display differently on a printout than onscreen, it can check whether the canvas is static. It can also retrieve the platform-dependent print job data from the canvas if it needs more information (for instance, to tell whether it is printing to a PostScript printer.)
Printing support, therefore, turns into two tasks: managing the print job and page layout when one is the root part, and imaging oneself onto a printing canvas. We’ll cover these in separate sections.
Note: We have provided a new utility class called CPrinter that takes care of almost all the work of running a basic Mac™ OS print job. It supports both QuickDraw and QuickDraw GX. Like all OpenDoc utilities it is supplied on an as-is basis, and you are encouraged to root through the source code to improve it or rewrite it or steal bits of it to meet your needs. You can find it with the other utilities, in source files Printer.cpp, PrinterQD.cpp and PrinterGX.cpp, and header Printer.h.
Managing the Print Job and Page Layout
As with imaging, OpenDoc provides no API for managing print jobs; you must use your operating system’s native API to do this. (However, an OpenDoc-based framework will probably provide support for printing; check your local listings.) In this recipe we will use the Macintosh Toolbox. Once you have set up a print job, you stuff it into a new ODCanvas object and use that canvas as the basis for layout and imaging.
There are two kinds of page layout a part can implement; which one you choose depends on how WYSIWYG your part is.
In the first and simpler method, the printed page has the same layout as your onscreen apperance. After you create a printing canvas, you create a new facet on the frame to be printed, attach that facet to the printing canvas, and image the facet (and any embedded facets.) This is what the CPrinter utility handles.
The second method is more complex but allows the printed page to have a different layout than the onscreen representation. To allow a new layout, you must create a new frame for your part on the printing canvas, also adding frames for all your embedded parts. In this process, the embedded parts (if they in turn want to lay themselves out differently on the printout) can use frame negotiation to change their size or position.
The basic steps are:
1. Retrieve any persistent print job settings (such as page setup information).
2. Display the standard printing dialog to the user.
3. Tell the operating system to start the print job.
4. Create a new static canvas, and stuff references to the print job and its drawing environment into the canvas.
5. Create a new frame or facet (depending on your printing-layout model) for yourself on the printing canvas.
6. Draw the root facet of the printing canvas (and its embedded facets, if any.)
7. If your content doesn’t fit on one page, scroll the root facet (by offsetting its external transform and clipshape) and draw the next page; repeat until finished.
8. Close the print job.
Rather than reproduce sample code here, we direct your attention to the CPrinter utility described earlier, which is included with the other OpenDoc utilities on this CD. The source files (Printer.h, Printer.cpp, PrinterQD.cpp, PrinterGX.cpp) contain working sample code that handles all of these steps.
QuickDraw GX and Printing. The Mac currently supports two printing architectures: QuickDraw and QuickDraw GX. The latter is much more powerful and functional, but its intrinsic API is quite different. It does support an emulation mode that handles the older API. However, once an application has made any GX calls, the app is assumed to be GX-savvy and emulation of the old printing API is disabled. Since OpenDoc's imaging subsystem uses GX quite heavily if it's available (mostly for ODShape operations), all processes that use OpenDoc are considered GX-savvy. Therefore, the root part must use the GX printing API instead of the old printing API whenever GX is available. Fortunately, supporting the new API, even for parts that don't make any other use of GX, is relatively simple, and the user benefits by getting much-improved dialog boxes for page setup and printing, plus access to powerful printing filters. The whole process is described in detail by Dave Hersey in issue 19 of ‘develop’ magazine.
Imaging Onto a Printing Canvas
Drawing to a printer is typically almost exactly like drawing to the screen (depending on what graphics system you are using.) As usual, your part’s Draw method will be called when it’s time to draw a facet, and it should use the facet’s canvas’ PlatformCanvas, cast to the appropriate graphics system type (such as a GrafPtr or gxViewPort on the Macintosh), to do its imaging.
To determine whether the canvas is static (non-interactive), you can use the IsStatic method of the canvas. If the canvas is static, you may not want to draw purely interactive features such as scroll bars. Remember that, while a print job is always static, there can be other kinds of static canvases, such as onscreen page previews; a static canvas is therefore no guarantee that a print job is in progress.
To determine whether the facet is being printed, you can use the HasPlatformPrintJob method of the canvas. If it returns kODTrue for one of the two Mac graphics systems, you can then call GetPlatformPrintJob to get the print job data (which on the Mac is a THPrint handle when using regular QuickDraw, or a gxJob reference when using GX.) You can use this data to determine features of the print job.
On the Macintosh, there is a complication involved with printing to a PostScript printer using classic QuickDraw. The LaserWriter driver does not handle Regions, so you will not be able to use calls such as SetClip to set up your facet’s clipping before drawing into it. The workaround is to emit some PostScript code that sets up a clipping path for the duration of your drawing.
Fortunately, if you use the FocusLib utility for all drawing into your facets, this is taken care of for you. If you do not use FocusLib for regular imaging, you can still use its BeginPostScriptClip and EndPostScriptClip functions to do the clipping as necessary.
References
The OpenDoc recipe Determining Print Resolution.
The OpenDoc CPrinter utility (source files Printer.h, Printer.cpp, PrinterQD.cpp, PrinterGX.cpp)
Macintosh Tech Note PR10: “A Print Loop That Cares”.
“Adding QuickDraw GX Printing To QuickDraw Applications” by Dave Hersey; in issue 19 of ‘develop’ magazine.
